home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / hugearr.zip / HUGEARR.TXT < prev    next >
Text File  |  1992-04-02  |  18KB  |  554 lines
  1.  
  2.                                 HUGEARR.DLL
  3.                Huge array support for Microsoft Visual Basic
  4.  
  5.               from Microsoft Product Support Services 6/4/91
  6.               with additions by various authors
  7.  
  8. The following information applies to Microsoft Visual Basic
  9. programming system version 1.0 for Microsoft Windows, and to Microsoft
  10. Windows 3.0 Software Development Kit (SDK).
  11.  
  12. HUGEARR.DLL is a dynamic-link library (DLL) which contains functions
  13. for creation, maintenance, and deletion of arrays larger than 64K from
  14. Microsoft Visual Basic version 1.00 for Windows. This DLL also gives
  15. the ability to create arrays with more than 32,767 (32K) elements per
  16. dimension, and to redimension arrays while preserving the data inside
  17. of the arrays.
  18.  
  19. To use the functions in HUGEARR.DLL, simply copy the declarations
  20. contained in HUGEARR.VBG into your global module in Visual Basic, copy
  21. the declarations in HUGEARR.VBM into any module, and copy HUGEARR.DLL
  22. to your Windows directory. The functions can then be used like any other
  23. Windows DLL function.
  24.  
  25. HUGEARR.DLL allocates memory using the Windows API function
  26. GlobalAlloc. This means that the largest array that can be allocated
  27. is 1 MB in standard mode, and 64 MB in 386 enhanced mode for Windows.
  28.  
  29. The following routines are contained in HUGEARR.DLL. For a complete
  30. description of the parameters and/or return values of these routines,
  31. see Visual Basic's Declare statement for the routine in question in
  32. the file HUGEARR.VBM.
  33.  
  34. HUGEARR.DLL Language Reference:
  35. ------------------------------
  36.  
  37. -------------------------------------------------------------------------
  38. VBHugeDim:
  39.  
  40. Action: Dimensions an array and returns a handle to that array.
  41.  
  42. Syntax: VBHugeDim(recsize%, limit&)
  43.  
  44. Argument       Description
  45. --------       -----------
  46.  
  47. recsize%       The size of each element in the array.  (i.e. an integer
  48.                would be 2, a double would be 8.)  You can use the Len()
  49.                function to determine the size of any data type if you are
  50.                unsure.
  51.  
  52. limit&         The upper bound of the array.  The lower bound of all arrays
  53.                is 0, so for example: 'VBHugeDim(2, 10)' would create an
  54.                integer array of elements 0 through 10.
  55.  
  56. Remarks:
  57. -------
  58.  
  59. You should not try to create a huge array of variable-length strings, or of
  60. a user-defined type that contains variable-length strings.  Visual Basic's
  61. string handling routines would not know of the existence of any string that
  62. was controlled by HUGEARR.DLL, and a UAE ("Unrecoverable Application Error")
  63. would probably result.  Fixed-length strings are okay though.
  64.  
  65. VBHugeDim returns a handle to the array that was created, and that handle is
  66. used when referring to that array with other commands.  If an error
  67. occurred (such as out of memory), it will return a negative number.  Error
  68. codes are detailed below under the section entitled 'Error Codes'.
  69.  
  70. Example:
  71. -------
  72.  
  73. Sub Command1_Click()
  74.      Dim hArray as integer
  75.      Dim variable as SomeUserDefinedType
  76.  
  77.      hArray = VBHugeDim(Len(variable), 10)
  78.      If hArray < 0 Then
  79.           print "Error dimensioning array:"; hArray
  80.           Stop
  81.      End If
  82.           .
  83.           .
  84.           .
  85.      i% = VBHugeErase(hArray)
  86. End Sub
  87.  
  88. -------------------------------------------------------------------------
  89. VBHugeErase:
  90.  
  91. Action: Erases an array that was previously dimensioned using VBHugeDim.
  92.  
  93. Syntax: VBHugeErase(hArray%)
  94.  
  95. Argument       Description
  96. --------       -----------
  97.  
  98. hArray%        The handle to the array.  (The same handle that was returned
  99.                by VBHugeDim.)
  100.  
  101. Remarks:
  102. --------
  103.  
  104. You should be sure to VBHugeErase all arrays that were VBHugeDim'd.  Failing to
  105. do so would cause the memory used by the array to not be freed up until the
  106. application quits.  If many arrays are dimensioned but never erased memory
  107. would keep being allocated without being freed, eventually degrading system
  108. performance.
  109.  
  110. Example:  Refer to the example for VBHugeDim.
  111.  
  112. -------------------------------------------------------------------------
  113. VBHugeRedim:
  114.  
  115. Action:  Redimensions an array created with VBHugeDim to a different size.
  116.  
  117. Syntax:  VBHugeRedim(hArray%, limit&)
  118.  
  119. Argument       Description
  120. --------       -----------
  121.  
  122. hArray%        The handle to the array to redimension.
  123.  
  124. limit&         The new upper bound of the array.
  125.  
  126. Remarks:
  127. --------
  128.  
  129. VBHugeRedim, unlike Visual Basic's ReDim, preserves all the data in the
  130. array.  If you want to erase the contents of the array, you should erase it
  131. and the dimension it again.
  132.  
  133. If the size of the array would go over 64K when it is redimensioned, it is
  134. subject to the same size restrictions detailed in the discussion of
  135. VBHugeDim.
  136.  
  137. You cannot change the size of the elements in the array, only the number of
  138. elements.
  139.  
  140. Example:
  141. --------
  142.  
  143. Sub Command1_Click()
  144.      .
  145.      .
  146.      i% = VBHugeRedim(hArray, 50)
  147.      if i% < 0 then
  148.           print "error redimensioning array:"; hArray
  149.           stop
  150.      End If
  151.  
  152.      e% = VBHugeErase(hArray)
  153. End Sub
  154.  
  155. -------------------------------------------------------------------------
  156. VBHugeGet, VBHugeSet:
  157.  
  158. Action:  Gets or sets the contents of an array element.
  159.  
  160. Syntax:  VBHugeGet(hArray%, el&, variable)
  161.          VBHugeSet(hArray%, el&, variable)
  162.  
  163. Argument       Description
  164. --------       -----------
  165.  
  166. hArray%        The handle to the array.
  167.  
  168. el&            The element of the array to set or get the data from.
  169.  
  170. variable       The variable to get into, or to set the array from.
  171.  
  172. Remarks:
  173. --------
  174.  
  175. It is extremely important that the type for the variable passed to
  176. VBHugeGet or VBHugeSet matches that type of the variable used in the
  177. VBHugeDim statement, if the types are of different lengths, you will mostly
  178. likely get a UAE or overwrite other data.  If you want to be sure that the
  179. types match you can use the Alias keyword when you declare the function to
  180. introduce type checking.  Refer to the section below entitled 'Aliasing'
  181. for more information on aliases.
  182.  
  183. Example:
  184. --------
  185. Sub Command2_Click()
  186.      .
  187.      .
  188.      .
  189.      hArray = VBHugeDim(len(i%), 10)
  190.      If hArray < 0 Then Stop
  191.      e% = VBHugeSet(hArray, 1, 54%)               ' puts 54 into element #1
  192.      If e% < 0 Then Stop                ' check error code
  193.      e% = VBHugeGet(hArray, 1, i%)           ' get element #1 into i%
  194.      Print i%
  195.  
  196.      e% = VBHugeErase(hArray)
  197. End Sub
  198.  
  199. -------------------------------------------------------------------------
  200. VBHugeGetNum, VBHugeSetNum:
  201.  
  202. Action:  Gets or sets the contents of multiple array elements.
  203.  
  204. Syntax:  VBHugeGetNum(hArray%, el&, nelem%, variable)
  205.          VBHugeSetNum(hArray%, el&, nelem%, variable)
  206.  
  207. Argument       Description
  208. --------       -----------
  209.  
  210. hArray%        The handle to the array.
  211.  
  212. el&            The first element of the array to set or get the data from.
  213.  
  214. nelem%         The number of elements to be set or fetched.
  215.  
  216. variable       The variable to get into, or to set the array from.
  217.  
  218. Remarks:
  219. --------
  220. See the Remarks for VBHugeGet, VBHugeSet.
  221.  
  222. Example:
  223. --------
  224. Sub Command2_Click()
  225.      .
  226.      .
  227.      Dim VBArray() as Double
  228.      ReDim VBArray(1 to 1000)
  229.      ' Assign something to the elements in VBArray.
  230.      .
  231.      .
  232.  
  233.      hArray = VBHugeDim(len(i#), 1000)
  234.      If hArray < 0 Then Stop
  235.  
  236.      ' Copy 1000 elements from VB array VBArray(1...1000) to huge array.
  237.      e% = VBHugeSetNum(hArray, 1, 1000, VBArray(1))
  238.      ' check error code
  239.      If e% < 0 Then Stop
  240.  
  241.      ' Copy 1000 elements from huge array to VB array VBArray(1...1000).
  242.      e% = VBHugeGetNum(hArray, 1, 1000, VBArray(1))
  243.  
  244.      e% = VBHugeErase(hArray)
  245. End Sub
  246.  
  247. ------------------------------------------------------------------------
  248. VBHugeSave:
  249.  
  250. Action:  Saves the specified number of elements of a huge array to the
  251.          named file.
  252.  
  253. Syntax:  VBHugeSave(hArray%, NEl&, RecLen%, Fn$)
  254.  
  255. Remarks:
  256. -------
  257.  
  258. The number of elements to save as well as the size of each element,
  259. together with the full filen